---
description: Rotate database secrets without restarting Hasura GraphQL Engine
sidebar_label: Dynamic Secrets
keywords:
  - hasura
  - docs
  - deployment
  - dynamic secrets
  - rotate secrets
sidebar_position: 9
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Thumbnail from '@site/src/components/Thumbnail';
import ProductBadge from '@site/src/components/ProductBadge';

# Dynamic Secrets

<ProductBadge ce self />

## Introduction

Dynamic secrets allow rotating database credentials without requiring you to restart the Hasura GraphQL Engine. Upon
enabling this feature, database connection strings will be read from a configured file for each new connection or upon
encountering a connection error.

## Configuration

:::tip Enabling this feature

To enable this feature, the environment variable `HASURA_GRAPHQL_DYNAMIC_SECRETS_ALLOWED_PATH_PREFIX` must be set and
non-empty. File paths used with this feature must start with the prefix set in this environment variable. See
[Dynamic Secrets Allowed Path Prefix](/deployment/graphql-engine-flags/reference.mdx#dynamic-secrets-allowed-path-prefix)
for reference.

:::

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

To add a new Postgres database with this feature, navigate to `Data` tab and click on `Data Manager`. Choose Postgres
and click `Connect Existing Database`. Choose `Dynamic URL` in the options and provide the path of the file where the
database connection string can be read from.

<Thumbnail
  src="/img/databases/postgres/dynamic-secrets/dynamic-secrets.png"
  alt="Dynamic secrets configuration for Postgres"
/>

</TabItem>
<TabItem value="cli" label="CLI">

Head to the `/metadata/databases/databases.yaml` file and add the database configuration as below:

```yaml
- name: pgDatabase
  kind: postgres
  configuration:
    connection_info:
      # highlight-start
      database_url:
        dynamic_from_file: /secrets/dbCredentials
      isolation_level: read-committed
      # highlight-end
      use_prepared_statements: false
```

Apply the Metadata by running:

```bash
hasura metadata apply
```

</TabItem>
<TabItem value="api" label="API">

You can add data source with dynamic secrets using the
[pg_add_source](/api-reference/metadata-api/source.mdx#metadata-pg-add-source) Metadata API.

</TabItem>
</Tabs>

## Configuration for metadata database

To enable rotating secrets for your metadata database, the environment variable `HASURA_GRAPHQL_METADATA_DATABASE_URL`
must be set as `dynamic-from-file:///path/to/file`. The connection string to the metadata database will be read from
this file. See [Metadata Database URL](/deployment/graphql-engine-flags/reference.mdx/#metadata-database-url) for
reference.

## Template variables

Dynamic secrets can be used in template variables for data connectors. See
[Template variables](/databases/database-config/data-connector-config.mdx/#template) for reference.

## Forcing secret refresh

If the environment variable `HASURA_SECRETS_BLOCKING_FORCE_REFRESH_URL=<url>`
is set, on each connection failure the server will POST to the specified URL the payload:

```
{"filename": <path>}
```

It is expected that the responding server will return only after refreshing the
secret at the given filepath. [hasura-secret-refresh](https://github.com/hasura/hasura-secret-refresh) 
follows this spec.
